home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / share / pyshared / pycountry / README.txt < prev    next >
Encoding:
Text File  |  2010-06-24  |  4.1 KB  |  189 lines
  1. =========
  2. pycountry
  3. =========
  4.  
  5. pycountry provides the ISO databases for the standards:
  6.  
  7. 639
  8.   Languages
  9.  
  10. 3166
  11.   Countries
  12.  
  13. 3166-2
  14.   Subdivisions of countries
  15.  
  16. 4217
  17.   Currencies
  18.  
  19. 15924
  20.   Scripts
  21.  
  22. The package includes a copy from Debian's `pkg-isocodes` and makes the data
  23. accessible through a Python API.
  24.  
  25. Translation files for the various strings are included as well.
  26.  
  27.  
  28. Countries (ISO 3166)
  29. ====================
  30.  
  31. Countries are accessible through a database object that is already configured
  32. upon import of pycountry and works as an iterable:
  33.  
  34.   >>> import pycountry
  35.   >>> len(pycountry.countries)
  36.   246
  37.   >>> list(pycountry.countries)[0]
  38.   <pycountry.db.Country object at 0x...>
  39.  
  40. Specific countries can be looked up by their various codes and provide the
  41. information included in the standard as attributes:
  42.  
  43.   >>> germany = pycountry.countries.get(alpha2='DE')
  44.   >>> germany
  45.   <pycountry.db.Country object at 0x...>
  46.   >>> germany.alpha2
  47.   'DE'
  48.   >>> germany.alpha3
  49.   'DEU'
  50.   >>> germany.numeric
  51.   '276'
  52.   >>> germany.name
  53.   'Germany'
  54.   >>> germany.official_name
  55.   'Federal Republic of Germany'
  56.  
  57. Note that historic countries, defined by the ISO 3166-3 sub-standard are not
  58. included in this list.
  59.  
  60. Country subdivisions (ISO 3166-2)
  61. =================================
  62.  
  63. The country subdivisions are a little more complex than the countries itself
  64. because they provide a nested and typed structure.
  65.  
  66. All subdivisons can be accessed directly:
  67.  
  68.   >>> len(pycountry.subdivisions)
  69.   4548
  70.   >>> list(pycountry.subdivisions)[0]
  71.   <pycountry.db.Subdivision object at 0x...>
  72.  
  73. Subdivisions can be accessed using their unique code and provide at least
  74. their code, name and type:
  75.  
  76.   >>> de_st= pycountry.subdivisions.get(code='DE-ST')
  77.   >>> de_st.code
  78.   'DE-ST'
  79.   >>> de_st.name
  80.   'Sachsen-Anhalt'
  81.   >>> de_st.type
  82.   'State'
  83.   >>> de_st.country
  84.   <pycountry.db.Country object at 0x...>
  85.  
  86. Some subdivisions specify another subdivision as a parent:
  87.  
  88.   >>> al_br = pycountry.subdivisions.get(code='AL-BU')
  89.   >>> al_br.code
  90.   'AL-BU'
  91.   >>> al_br.name
  92.   u'Bulqiz\xeb'
  93.   >>> al_br.type
  94.   'District'
  95.   >>> al_br.parent_code
  96.   'AL-09'
  97.   >>> al_br.parent
  98.   <pycountry.db.Subdivision object at 0x...>
  99.   >>> al_br.parent.name
  100.   u'Dib\xebr'
  101.  
  102. The divisions of a single country can be queried using the country_code index:
  103.  
  104.   >>> len(pycountry.subdivisions.get(country_code='DE'))
  105.   16
  106.  
  107.   >>> len(pycountry.subdivisions.get(country_code='US'))
  108.   57
  109.  
  110.  
  111. Scripts (ISO 15924)
  112. ===================
  113.  
  114. Scripts are available from a database similar to the countries:
  115.  
  116.   >>> len(pycountry.scripts)
  117.   146
  118.   >>> list(pycountry.scripts)[0]
  119.   <pycountry.db.Script object at 0x...>
  120.  
  121.   >>> latin = pycountry.scripts.get(name='Latin')
  122.   >>> latin
  123.   <pycountry.db.Script object at 0x...>
  124.   >>> latin.alpha4
  125.   'Latn'
  126.   >>> latin.name
  127.   'Latin'
  128.   >>> latin.numeric
  129.   '215'
  130.  
  131.  
  132. Currencies (ISO 4217)
  133. =====================
  134.  
  135. The currencies database is, again, similar to the ones before:
  136.  
  137.   >>> len(pycountry.currencies)
  138.   182
  139.   >>> list(pycountry.currencies)[0]
  140.   <pycountry.db.Currency object at 0x...>
  141.  
  142.   >>> argentine_peso = pycountry.currencies.get(letter='ARS')
  143.   >>> argentine_peso
  144.   <pycountry.db.Currency object at 0x...>
  145.   >>> argentine_peso.letter
  146.   'ARS'
  147.   >>> argentine_peso.name
  148.   'Argentine Peso'
  149.   >>> argentine_peso.numeric
  150.   '032'
  151.  
  152.  
  153. Languages (ISO 639)
  154. ===================
  155.  
  156. The languages database is similar too:
  157.  
  158.   >>> len(pycountry.languages)
  159.   486
  160.   >>> list(pycountry.languages)[0]
  161.   <pycountry.db.Language object at 0x...>
  162.  
  163.   >>> aragonese = pycountry.languages.get(alpha2='an')
  164.   >>> aragonese.alpha2
  165.   'an'
  166.   >>> aragonese.bibliographic
  167.   'arg'
  168.   >>> aragonese.terminology
  169.   'arg'
  170.   >>> aragonese.name
  171.   'Aragonese'
  172.  
  173. Locales
  174. =======
  175.  
  176. Locales are available in the `pycountry.LOCALES_DIR` subdirectory of this
  177. package. The translation domains are called `isoXXX` according to the standard
  178. they provide translations for. The directory is structured in a way compatible
  179. to Python's gettext module.
  180.  
  181. Here is an example translating language names:
  182.  
  183.   >>> import gettext
  184.   >>> german = gettext.translation('iso_3166', pycountry.LOCALES_DIR,
  185.   ...                              languages=['de'])
  186.   >>> german.install()
  187.   >>> _('Germany')
  188.   'Deutschland'
  189.